package com.googlecode.skald.client.affordances;

/**
 * An enum of different menu structure options to use when building an 
 * affordances menu.  See each option for more details.
 * 
 * @see Affordances#getMenu(java.util.List, java.util.EnumSet, Class)
 */
public enum MenuOption {

  /**
   * Any parallel menus with the same initial display element text(s) are 
   * collapsed into a single menu option with differing submenu tails.
   * For example:
   * <pre>
   * Throw &gt; ball
   * Throw &gt; stick
   * </pre>
   * would be collapsed in to 
   * <pre>
   * Throw &gt; ball
   *         stick
   * </pre>
   * Similarly, 
   * <pre>
   * Throw &gt; rock &gt; at &gt; dark elf
   * Throw &gt; rock &gt; at &gt; orc
   * </pre>
   * would be collapsed in to 
   * <pre>
   * Throw &gt; rock &gt; at &gt; dark elf
   *                              orc
   * </pre>
   * 
   */
  COLLAPSE_VERTICALLY,
  
  /**
   * Menus with only a single item are instead combined with their parent
   * option.  For example, this menu:
   * <pre>
   * Get &gt; axe
   * Throw &gt; rock &gt; at &gt; dwarf
   * Throw &gt; rock &gt; at &gt; orc
   * </pre>
   * would become:
   * <pre>
   * Get axe
   * Throw rock at &gt; dwarf
   * Throw rock at &gt; orc
   * </pre>
   * Or if combined with {@link #COLLAPSE_VERTICALLY}, this would give:
   * <pre>
   * Get axe
   * Throw rock at &gt; dwarf
   *                 orc
   * </pre>
   */
  COLLAPSE_HORIZONTALLY, 

  /**
   * When using {@link #COLLAPSE_HORIZONTALLY}, this option preserves a 
   * "verb-only" format at the top-level of the menu. For example:
   * <pre>
   * Get &gt; axe
   * Throw &gt; rock &gt; at &gt; dwarf
   * </pre>
   * would become:
   * <pre>
   * Get &gt; axe
   * Throw &gt; rock at dwarf
   * </pre>
   * <p>
   * Without {@link #COLLAPSE_HORIZONTALLY}, this option does nothing.
   */
  DO_NOT_COLLAPSE_INTO_TOP_LEVEL,
  
}
